home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / STK100.ZIP / DWS.PAS < prev    next >
Pascal/Delphi Source File  |  1995-02-17  |  13KB  |  415 lines
  1. (******************************************************************************
  2. File:          dws.pas
  3. Version:     1.0
  4. Tab stops: every 2 collumns
  5. Project:     The Sound ToolKit
  6. Copyright: 1994 DiamondWare, Ltd.  All rights reserved.
  7. Written:     Keith Weiner
  8. Purpose:     Creates dws.tpu
  9. History:     KW 10/09/94 Started
  10.                      EL 11/27/94 Finalized for v1.0
  11.  
  12. NB: The dwt (timer) code is not compatible with source profilers
  13. ******************************************************************************)
  14.  
  15.  
  16. unit DWS;
  17.  
  18. interface
  19.  
  20.  
  21.  
  22. const
  23.  
  24. (*****************************************************************************)
  25.     (*
  26.      . The following is the complete list of possible values for dws_errno.
  27.      . dws_errno may be set by any dws_ function.  Check its value whenever
  28.      . the return value of a dws_ function is 0 (error).
  29.     *)
  30.     dws_EZERO                                                  =    0;
  31.  
  32.     (* The following 3 errors may be triggered by any dws_ function *)
  33.     dws_NOTINITTED                                         =    1;
  34.     dws_ALREADYINITTED                                 =    2;
  35.     dws_NOTSUPPORTED                                     =    3;
  36.  
  37.     (* The following 4 errors may be triggered by dws_DetectHardWare *)
  38.     dws_DetectHardware_UNSTABLESYSTEM  =    4;
  39.     dws_DetectHardware_BADBASEPORT         =    5;
  40.     dws_DetectHardware_BADDMA                  =    6;
  41.     dws_DetectHardware_BADIRQ                  =    7;
  42.  
  43.     (* The following error may be triggered by dws_Kill *)
  44.     dws_Kill_CANTUNHOOKISR                         =    8;
  45.  
  46.     (* The following error may be triggered by any dws_X (mixer) function *)
  47.     dws_X_BADINPUT                                         =    9;
  48.  
  49.     (* The following 3 errors may be triggered by any dws_D (dig) function *)
  50.     dws_D_NOTADWD                                          =    10;
  51.     dws_D_NOTSUPPORTEDVER                          =    11;
  52.     dws_D_INTERNALERROR                              =    12;
  53.  
  54.     (* The following error may be triggered by dws_DPlay *)
  55.     dws_DPlay_NOSPACEFORSOUND                  =    13;
  56.  
  57.     (* The following 2 errors may be triggered by dws_DSetRate *)
  58.     dws_DSetRate_FREQTOLOW                         =    14;
  59.     dws_DSetRate_FREQTOHIGH                      =    15;
  60.  
  61.     (* The following 3 errors may be triggered by dws_MPlay *)
  62.     dws_MPlay_NOTADWM                                  =    16;
  63.     dws_MPlay_NOTSUPPORTEDVER                  =    17;
  64.     dws_MPlay_INTERNALERROR                      =    18;
  65. (*---------------------------------------------------------------------------*)
  66.  
  67.  
  68.     (*
  69.      . The follwing section defines bitfields which are used by various
  70.      . dws_ functions.    Each bit in a bitfield, by definition, may be
  71.      . set/reset independantly of all other bits.
  72.     *)
  73.  
  74.     (* The following 2 consts indicate the capabilities of the user's hardware *)
  75.     dws_capability_FM                                  = $0001;
  76.     dws_capability_DIG                                 = $0002;
  77.  
  78.  
  79.     (* The following 2 consts indicate the status of specified digital sounds *)
  80.     dws_DSOUNDSTATUSPLAYING                      = $0001;
  81.     dws_DSOUNDSTATUSSEQUENCED                  = $0002;
  82.  
  83.  
  84.     (* The following 2 consts indicate the status of music playback *)
  85.     dws_MSONGSTATUSPLAYING                         = $0001;
  86.     dws_MSONGSTATUSPAUSED                          = $0002;
  87.  
  88.     (*
  89.      . Below are the timer rates supported by DWT.    Anything in between
  90.      . the listed values will cause the DOS/BIOS clock to tick erratically
  91.      . and is thus not allowed.  Any value higher than 145.6 Hz means
  92.      . you have some very special circumstances; DWT won't fit your needs
  93.      . anyway.
  94.     *)
  95.     dwt_18_2HZ                                                 = 0;                      (*18.2 Hz*)
  96.     dwt_36_4HZ                                                 = 1;                      (*36.4 Hz*)
  97.     dwt_72_8HZ                                                 = 2;                      (*72.8 Hz*)
  98.     dwt_145_6HZ                                              = 3;                      (*145.6 Hz*)
  99. (*****************************************************************************)
  100.  
  101.  
  102.  
  103. type
  104.  
  105.     (*
  106.      . The following section declares the record types used by the STK.  In each
  107.      . case, the user must create an instance of the record prior to making
  108.      . a call to an STK function which takes a pointer to it.  The STK does
  109.      . not keep a pointer to any of these records internally; after the call
  110.      . returns, you may deallocate it, if you wish.
  111.      .
  112.      . NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  113.     *)
  114.  
  115.  
  116.     (*
  117.      . dws_DetectHardWare can be told _not_ to autodetect particular values
  118.      . about the installed hardware.    This is useful if detecting DMA channel,
  119.      . for example, consistently causes a machine lockup.  To override the
  120.      . autodetect for a setting (causing the STK to accept it on faith),
  121.      . set the corresponding field in this record to the correct value.
  122.      . Otherwise, set the field to ffff hex.    Since the autodetect is reliable,
  123.      . this is the recommended course of action, except in cases of known
  124.      . problems.
  125.     *)
  126.     dws_DETECTOVERRIDES = record
  127.         baseport : word;                                    (*base addr of sound card (often 220) hex*)
  128.  
  129.         digdma     : word;                                    (*DMA channel*)
  130.         digirq     : word;                                    (*IRQ level*)
  131.  
  132.         reserved : array[1..10] of word;
  133.  
  134.     end;
  135.  
  136.  
  137.     (*
  138.      . A pointer to this record is passed to dws_DetectHardWare, which fills
  139.      . it in.  It is then passed unmodified to dws_Init.    If you plan on
  140.      . writing this record out to a file, it's important that you write
  141.      . the entire contents.  There is information (for internal STK use only)
  142.      . in the reserved[] field!
  143.     *)
  144.     dws_DETECTRESULTS = record
  145.         baseport     : word;                                (*base addr of sound card (often 220) hex*)
  146.  
  147.         capability : word;                                (*see constants, above*)
  148.  
  149.         (* The following 3 fields are only valid if FM music is supported *)
  150.         mustyp         : word;                                (*0=none, 1=OPL2*)
  151.         musnchan     : word;                                (*1=mono*)
  152.         musnvoice  : word;                                (*num hardware voices (11 for FM)*)
  153.  
  154.         (* The following 4 fields are only valid if digitized sound is supported *)
  155.         dignbits     : word;                                (*0=none, 8=8 bit*)
  156.         dignchan     : word;                                (*1=mono*)
  157.         digdma         : word;                                (*DMA channel*)
  158.         digirq         : word;                                (*IRQ level*)
  159.  
  160.         mixtyp         : word;                                (*1=software, 2+ is hardware*)
  161.  
  162.         reserved     : array[1..44] of byte;(*there are important values in here...*)
  163.  
  164.     end;
  165.  
  166.  
  167.     (*
  168.      . A pointer to this struct is passed as a parameter to dws_Init.  This
  169.      . allows the user to tell the STK to use less than the full capabilities
  170.      . of the installed sound hardware, and/or the user's sound board
  171.      . may not support every feature of the STK.
  172.     *)
  173.     dws_IDEAL = record
  174.         musictyp     : word;                 (*0=No Music, 1=OPL2*)
  175.  
  176.         digtyp         : word;                 (*0=No Dig, 8=8bit*)
  177.         digrate      : word;                 (*sampling rate, in Hz*)
  178.         dignvoices : word;                 (*number of voices (up to 16)*)
  179.         dignchan     : word;                 (*1=mono*)
  180.  
  181.         reserved     : array[1..6] of byte;
  182.  
  183.     end;
  184.  
  185.  
  186.     (*
  187.      . A pointer to this record is passed to dws_DPlay.
  188.      . Note that the soundnum field is filled in by dws_DPlay as a return value.
  189.     *)
  190.     dws_DPLAYREC = record
  191.         snd          : ^byte;                  (*pointer to buffer which holds a .DWD file*)
  192.         count      : word;                     (*number of times to play, or 0=infinite loop*)
  193.         priority : word;                     (*higher numbers mean higher priority*)
  194.         presnd     : word;                     (*soundnum to sequence sound _after_*)
  195.         soundnum : word;                     (*dws_DPlay returns a snd number from 10-65535*)
  196.  
  197.         reserved : array[1..20] of byte;
  198.  
  199.     end;
  200.  
  201.  
  202.     (* A pointer to this record is passed to dws_MPlay. *)
  203.     dws_MPLAYREC = record
  204.         track : ^byte;                         (*pointer to buffer which holds a .DWM file*)
  205.         count : word;                          (*number of times to play, or 0=infinite loop*)
  206.  
  207.         reserved : array[1..10] of byte;
  208.  
  209.     end;
  210. (*****************************************************************************)
  211.  
  212.  
  213.     dws_DOPTR = ^dws_DETECTOVERRIDES;
  214.     dws_DRPTR = ^dws_DETECTRESULTS;
  215.     dws_IDPTR = ^dws_IDEAL;
  216.     dws_DPPTR = ^dws_DPLAYREC;
  217.     dws_MPPTR = ^dws_MPLAYREC;
  218.  
  219.     dws_WDPTR = ^word;
  220.     dws_BTPTR = ^byte;
  221.  
  222.  
  223.  
  224. (*****************************************************************************)
  225.  
  226.  
  227. (*
  228.  . This function is callable at any time.  It returns the number of the
  229.  . last error which occured.
  230. *)
  231. function dws_ErrNo : word;
  232. (*---------------------------------------------------------------------------*)
  233.  
  234.  
  235. (*
  236.  . This procedure is called at the end of the timer ISR (interrupt service
  237.  . routine).    If you're using the optional DWT (DW Timer), this happens
  238.  . automagically.  If you wrote your own timer handler routine, you must
  239.  . call this function regularly.
  240. *)
  241. procedure dws_Update;
  242. (*---------------------------------------------------------------------------*)
  243.  
  244.  
  245. (*
  246.  . Each function in this section has a boolean return value.    A 0 (false)
  247.  . indicates that the function failed in some way.    In this case, call
  248.  . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  249.  . (true) indicates that all is well.
  250. *)
  251. function dws_DetectHardWare(dov : dws_DOPTR; dr : dws_DRPTR) : word;
  252.  
  253. function dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word;
  254.  
  255. (*
  256.  . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  257.  . terminates.
  258.  .
  259.  . NB: Trap critical errors.    Don't let DOS put up the
  260.  .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  261. *)
  262. function dws_Kill : word;
  263.  
  264.  
  265. (*
  266.  . The following 3 functions comprise the mixer section of the STK.  A
  267.  . value of 0 turns a channel off; a value of 255 is the loudest.
  268. *)
  269. function dws_XMaster(volume : word) : word;
  270.  
  271. function dws_XMusic(volume : word) : word;
  272.  
  273. function dws_XDig(volume : word) : word;
  274.  
  275.  
  276.  
  277. (*
  278.  . The following 10 functions comprise the digitized sound functions of
  279.  . the STK.  See the documentation for complete details.
  280. *)
  281. function dws_DPlay(dplay : dws_DPPTR) : word;
  282.  
  283. function dws_DSoundStatus(soundnum : word; result : dws_WDPTR) : word;
  284.  
  285. function dws_DSetRate(frequency : word) : word;
  286.  
  287. function dws_DGetRate(result : dws_WDPTR) : word;
  288.  
  289. (* This function is callable at any time*)
  290. function dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word;
  291.  
  292. function dws_DDiscard(soundnum : word) : word;
  293.  
  294. function dws_DDiscardAO(snd : dws_BTPTR) : word;
  295.  
  296. function dws_DClear : word;                     (*All*)
  297.  
  298. function dws_DPause : word;                     (*All*)
  299.  
  300. function dws_DUnPause : word;                 (*All*)
  301.  
  302.  
  303. (*
  304.  . The following 5 functions comprise the music functions of the STK.
  305.  . See the documentation for complete details.
  306. *)
  307. function dws_MPlay(mplay : dws_MPPTR) : word;
  308.  
  309. function dws_MSongStatus(status : dws_WDPTR) : word;
  310.  
  311. function dws_MClear : word;
  312.  
  313. function dws_MPause : word;
  314.  
  315. function dws_MUnPause : word;
  316. (*---------------------------------------------------------------------------*)
  317.  
  318.  
  319. (*
  320.  . The following 5 functions/procedures comprise the timer functions of the STK.
  321.  . See the documentation for complete details.
  322. *)
  323.  
  324. (* See const declarations above for rates*)
  325. procedure dwt_Init(rate : word);
  326.  
  327. (*
  328.  . If the program has called dwt_Init, it _MUST_ call dwt_Kill before it
  329.  . terminates.
  330.  .
  331.  . NB: Trap critical errors.    Don't let DOS put up the
  332.  .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  333. *)
  334. procedure dwt_Kill;
  335.  
  336. (* The following 2 procedures affect the timer, but not the music *)
  337. procedure dwt_UnPause;
  338.  
  339. procedure dwt_Pause;
  340.  
  341. (*
  342.  .number of ticks since Beginning of World
  343. *)
  344. function dwt_MasterTick : longint;
  345. (*****************************************************************************)
  346.  
  347.  
  348.  
  349. implementation
  350.  
  351.  
  352. function dws_ErrNo : word; external;
  353.  
  354. procedure dws_Update; external;
  355.  
  356.  
  357. function dws_DetectHardWare(dov : dws_DOPTR; dr : dws_DRPTR) : word; external;
  358.  
  359. function dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word; external;
  360.  
  361. function dws_Kill : word; external;
  362.  
  363.  
  364. function dws_XMaster(volume : word) : word; external;
  365.  
  366. function dws_XMusic(volume : word) : word; external;
  367.  
  368. function dws_XDig(volume : word) : word; external;
  369.  
  370.  
  371. function dws_DPlay(dplay : dws_DPPTR) : word; external;
  372.  
  373. function dws_DSoundStatus(soundnum : word; result : dws_WDPTR) : word; external;
  374.  
  375. function dws_DSetRate(frequency : word) : word; external;
  376.  
  377. function dws_DGetRate(result : dws_WDPTR) : word; external;
  378.  
  379. function dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word; external;
  380.  
  381. function dws_DDiscard(soundnum : word) : word; external;
  382.  
  383. function dws_DDiscardAO(snd : dws_BTPTR) : word; external;
  384.  
  385. function dws_DClear : word; external;
  386.  
  387. function dws_DPause : word; external;
  388.  
  389. function dws_DUnPause : word; external;
  390.  
  391.  
  392. function dws_MSongStatus(status : dws_WDPTR) : word; external;
  393.  
  394. function dws_MPlay(mplay : dws_MPPTR) : word; external;
  395.  
  396. function dws_MClear : word; external;
  397.  
  398. function dws_MPause : word; external;
  399.  
  400. function dws_MUnPause     : word; external;
  401.  
  402.  
  403. procedure dwt_Init(rate : word); external;
  404.  
  405. procedure dwt_Kill; external;
  406.  
  407. procedure dwt_Pause; external;
  408.  
  409. procedure dwt_UnPause; external;
  410.  
  411. function dwt_MasterTick : longint; external;
  412.  
  413.  
  414. end.
  415.